eRez Imaging Server 3.1

Configuration Guide

04-may-2005

NOTE: Version 3.0 and later of the eRez Imaging Server comes with a web based configuration tool that allows you to edit almost all settings of the configuration files.

So, unless you want to read or write the eRez configuration files from your own applications or need to tweak some of the rarely used settings, you can skip reading this document.

Table of contents

Overview. 2

First Steps. 3

User Administration. 4

Groups. 5

Users. 5

Shared Folder Administration. 7

Template Creation. 9

Format 9

Downloadformat 10

Miscellaneous System Setting. 14

The <erez-home> element 14

The <emailer > element 14

The <flat-images > element 14

The <imagefactory> element 15

The <downloadfactory> element 15

The <browser> element 16

The <iccprofiles> element 16

The <mactext> element 17

The hotfolder element 18

The encoding element 18

The metadatacache element 18

The encryption element 18

Overview

This document describes the various configuration files and how they are used to configure the eRez Imaging Server. The server will check for changes to the configuration files every 30 seconds and automatically reconfigure itself accordingly.

All configuration files are in XML format. If you don’t know XML but know the basics of HTML you will be soon be familiar with the format. But, don’t panic If you have never seen an XML or HTML document before. XML is not rocket science and you will quickly learn enough of the syntax to deal with the eRez configuration files. If you want to learn the basics before you continue you can run though one of the many online tutorials on the web like http://www.w3schools.com/xml/.

The main configuration file is called erez.xml and is placed in the WEB-INF folder in the erez2 folder. This is what the standard file looks like:

<?xml version="1.0" encoding="iso-8859-1"?>

<yawah>

</yawah>

This file simply contains references to 5 other configuration files normally located in the WEB-INF/configuration folder. You only need to edit erez.xml if you have moved your configuration files to a different location. You might want to do that in order to to share the same set of configuration files between multiple eRez server.

The XML files can be edited using a standard text editor. If you have Microsoft Internet Explorer installed on your machine you can use it verify the syntax of the XML files. When opening the erez.xml in Internet Explorer it would look like this:

Microsoft Internet Explorer can be used to verify the syntax of XML files

and present the content in a more readable way.

The 5 files used by erez are:

system.xml - contains miscellaneous.
users.xml – contains information about users and groups-
license.xml – contains licensing information. You won’t have to edit this one manually.
shares.xml – contains information about the shared folders.
formats.xml – contains predefined templates for the image file formats.

Among the very first things to do after installing eRez is to change the password for the “administrator” user account. This is done by editing the users.xml as explained in the next section.

First Steps

Among the first things you should do is to change the password for the “administrator” account and configure and enable the “emailer” settings.

To change the password for the administrator account please refer to “User Administration”.

To avoid unintentional sending of emails when the software is first installed sending of emails has been disabled. To enable emails refer to the chapter “The <emailer > element”.

User Administration

The default user.xml file looks like this:

<?xml version="1.0" encoding="iso-8859-1"?>

<!--

Admin User. Encrypted password created using the Apache

htpasswd utility: Typing: htpasswd -snb admin admin

Outputs: admin:{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc=

-->

<user

password="{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc="

email="administrator@yawah.com"

firstname="eRez"

lastname="Administrator"

</user>

<!--

Sample User with plain-text password.

-->

<user

password="user"

email="user@yawah.com"

firstname="eRez"

lastname="User"

</user>

</usersandgroups>

The text between the “<!—“ and “-->” are comments and ignored when the file is read by eRez.

The file starts with a standard XML header. Next comes a “tag” marking the beginning of the “usersandgroups” element. Inside this tag there can be any number of “group” and “user elements”.

Groups

A “group” element simply contains the name of a group. To add a third group called “friends” you simply add it to the document like this:

The “administrator” group is a special group. Only members of the administrator group will be able to check the status of the server and enter a license key.

Users

A “user” elements looks like this:

<user

password="user"

email="user@yawah.com"

firstname="eRez"

lastname="User"

</user>

The meaning of “login”, “password”, “email”, “firstname” and “lastname” attributes requires no further explanation. The value of the password attribute can either be a plain-text password or an encrypted password like in the “administrator” example:

<user

password="{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc="

email="administrator@yawah.com"

firstname="eRez"

lastname="Administrator"

</user>

Encrypted passwords start with the string “{SHA}” and are automatically identified by the eRez server as such. These encrypted passwords can be generated by means of the htpasswd utility that comes with the Apache web server.

The password for the administrator was generated by entering:

htpasswd -snb admin admin

It is very important to use the “s” option to specify SHA encryption. The ouputt looks like this:

admin:{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc=

The password to place in the users.xml is the part following the initial colonand starting with {SHA},

Individual users are assigned membership of a group by means of a “member” sub-element,

To add the user “user” to the new “friends” group you simple add an extra “member” element like this:

<user

password="user"

email="user@yawah.com"

firstname="eRez"

lastname="User"

</user>

You can add individual memberships of as many groups as you like to a single user. If you use “*” as the group name, the user will be given membership of ALL groups. This is the case for the administrator:

<user

password="{SHA}0DPiKuNIrrVmD8IUCuw1hQxNqZc="

email="administrator@yawah.com"

firstname="eRez"

lastname="Administrator"

</user>

Shared Folder Administration

The default shares.xml file looks like this:

<?xml version="1.0" encoding="iso-8859-1"?>

<yawah>

<mount

name="Format Samples"

path="WEB-INF/sample images/formats"

cache="WEB-INF/cache"

viewgroup="*"

listgroup="*"

downloadgroup="?"

uploadgroup="?"

editgroup="?"

deletegroup="administrator"

<mount

name="Color Management"

path="WEB-INF/sample images/cms"

cache="WEB-INF/cache"

viewgroup="?"

listgroup="users"

downloadgroup="administrator"

uploadgroup="administrator"

editgroup="administrator"

deletegroup="administrator"

</yawah>

Inside the “yawah” element there must be a “mount” for every folder that you want to share.

The various xxxgroup attributes define the groups to which a user must belong in order to carry out certain operations. Two special values for the xxxgroups attributes exist:

“? “ Means all known users (users with a valid login and password).
“*” Means everybody, including anonymous guests.

If one or more of the xxxgroup attributes are removed altogether, the operation(s) will be completely disabled. If for example you don’t want anybody (including the administrator) to be able delete and edit files and folders, you can delete the lines with the deletegroup and editgroup attributes:

<mount

name="Color Management"

path="WEB-INF/sample images/cms"

cache="WEB-INF/cache"

viewgroup="?"

listgroup="users"

downloadgroup="administrator"

uploadgroup="administrator"

After removing these lines no one will be able to delete or edit files or folders in the share.

Attributes for the mount element:

name	The public name of the share. This is the name that users will see when listing the contents of the server.
path	The local path to the directory with images and sub-directories. This can be a path to a local hard drive or a remote server like "\\HOST\SHARE\EREZ\STUFF" on a Windows System. The sample configuration file that ships with the software uses a special path: "WEB-INF/…”. "WEB-INF" is a special case supported in order to make the eRez Imaging Server work with sample images immediately after the installation. DO NOT PLACE YOUR OWN IMAGES OR CACHE IN THE WEB-INF DIRECTORY.
cache	The directory where derived images are stored for reuse. The same cache directory can be shared by several shares or you can use a separate cache for each.
viewgroup	The group to which a user must belong in order to view images.
listgroup	The group to which a user must belong in order to list the contents of the share. Without this group membership the share will be completely invisible to the user-
downloadgroup	The group to which a user must belong in order to download images.
uploadgroup	The group to which a user must belong in order to upload images.
editgroup	The group to which a user must belong in order to edit images and folders.
deletegroup	The group to which a user must belong in order to delete images and folders.
hotfolder	Setting this attribute to the value “0” disables monitoring and indexing of the files for full text search etc. All other values or omitting the attribute entirely leaves indexing and monitoring enabled.

Template Creation

The file formats.xml contains a “yawah” element with an arbitrary number of “format” and/or “downloadformat” elements. The “format” elements define the image templates for use with the real-time channel. The “downloadformat” elements define the image templates for use with the asynchronous – or download – channel.

This is what the “format” element for the thumbnail template looks like:

</format>

Format only has a single attribute. The rest of the data is defined as sub-elements. The individual values of the templates can be modified by specifying a different value as part of the image URL. Please refer to the HTTP Command Reference for more information on how to override the values from a template.

Format

Attributes for format:

name	The name of the template.
hidden	Optional. If this is set to “1” the template will not be displayed to the user.

Attributes for crop (optional format sub-element):

top	The part of the image to remove at the top. Must be in the range 0.0 (top) to 1.0 (bottom).
left	The part of the image to remove at the left. Must be in the range 0.0 (left) to 1.0 (right).
bottom	The amount of the image to remove at the bottom. Must be in the range 0.0 (top) to 1.0 (bottom).
right	The part of the image to remove at the right. Must be in the range 0.0 (left) to 1.0 (right).
angle	The rotation of the image in degrees.

Attributes for size (format sub-element):

width	The maximum width of the image in pixels.
height	The maximum height of the image in pixels.
keepaspect	Preserves the relative width and height of the source image (default). When this is disabled by setting the value to “0” the dimensions of the resulting image will be exactly as requested.
antialias	Optional. If this is set to “0” the default anti-alias filter will be disabled.

Attributes for color (format sub-element):

colorspace

Not currently used. MUST BE "sRGB" FOR FUTURE USE.

Attributes for sharpen (format sub-element):

amount

The amount of sharpening to apply to the image. Must be in the range -500 (heavy blur) to 500 (strong sharpening). A value of 0 applies no sharpening.

Attributes for output (format sub-element):

format	The image file format for the generated image. Legal values are: "jpeg" - standard JFIF formatted images. "flash" - JPEG compressed Flash movies. "png" - 256 color indexed PNG images (better than GIF and with no patent issues) "pdf" - JPEG or ZIP compressed Adobe PDF files (requires Adobe Acrobat Reader or similar) "eps"- Encapsulated Postscript images with 256 color TIFF preview. "tiff" - Tagged Image File Format.
quality	The quality of JPEG compressed images. Must be in the range 0 (poor quality/small image) to 100 (perfect quality/very large image). For PDF images a value of "0" means no JPEG compression and ZIP compression will be used instead. For PNG and EPS this attribute is ignored.
chromasubsampling	Enables downsampling of color information during JPEG compression (default). When setting this attribute to the value “0” this will be disabled the file size will increase as much as 30 percent. But the color information is preserved at full resolution. Certain computer generated images may appear blurry unless this option is disabled.

Attributes for fill (optional format sub-element):

color

The RGB background color used to pad the image in order to fill the template box. Uses standard web color format (e.g. ff0000 is red, 00ff00 is green etc..).

Attributes for watermark (optional format sub-element):

image

The local path and filename to an uncompressed RGB TIFF image with an alpha channel (transparency). This can be a path to a local harddrive or a remote server like "\\HOST\SHARE\EREZ\STUFF" on a Windows System. The sample configuration file that ships with the software uses a special path: "WEB-INF/overlays/*.tif". "WEB-INF" is a special case supported in order to make the eRez Imaging Server work with sample setup immediately after the installation. DO NOT PLACE YOUR OWN WATERMARK IMAGES IN THE WEB-INF DIRECTORY.

Downloadformat

Attributes for downloadformat:

name	The name of the template. This is the name used to refer to the template from an URL.
description	A human readable description that can be displayed to the user while choosing from the templates.

Attributes for size (downloadformat sub-element):

width	The maximum width of the image in pixels.
height	The maximum height of the image in pixels.

Attributes for interpolate (downloadformat sub-element):

maxscale

Maxscale defines the maximum enlargement of the source image in percent. The default value is 100. For example to allow the images to be enlarged (interpolated) by 20 percent use a value of 120.

action

Action controls the behavior of image processor when the source image does not contain sufficient data to create the destination image without breaking the maxscale barrier. Legal values are:
fail: This is the default and causes the job to fail.
max: The width and height of the destination image is decreased to the honor the maxscale setting.
ignore: The maxscale value is simply ignored, allowing the image to be interpolated without limits.

Attributes for color (downloadformat sub-element):

colorspace

The description of the ICC profile to use. This is NOT the filename - but the textual description as embedded in the profile. You can see a list of descriptions from the available profiles on the Server Status page. See the <iccprofiles> element above on how to add additional ICC profiles.
The special value "*" means no conversion should take place and that the target profile is identical to the source profile of the original image.

renderingintent

Optional rendering intent for the color transformation. Legal values are:

0: Perceptual

1: Relative Colorimetric

2: Saturation

3: Absolute Colorimetric

Attributes for sharpen (downloadformat sub-element):

amount

The amount of sharpening to apply to the image. Must be in the range -500 (heavy blur) to 500 (strong sharpening). A value of 0 applies no sharpening. The "sharpen" filter is best suited for low resolution output. Use "unsharpmask" instead for high resolution CMYK output.

Attributes for unsharpmask (downloadformat sub-element):

amount	The amount of sharpening to apply. The interpretation of "amount" has been designed to mimic the behavior of Adobe Photoshop - but you will have to experiment a little to get the optimum result. As an alternative you may consider using the simple "sharpen" filter for low resolution images.
radius	The radius of the gauss kernel used to calculate the unsharp value. The interpretation of "radius" has been designed to mimic the behavior of Adobe Photoshop - but you will have to experiment a little to get the optimum result.
threshold	This attribute is currently ignored and reserved for future use.

Attributes for output (downloadformat sub-element):

format	The image file format for the generated image. Legal values are: "jpeg" - standard JFIF formatted images. "pdf" - JPEG or ZIP compressed Adobe PDF files (requires Adobe Acrobat Reader or similar) "eps"- Encapsulated Postscript images with 256 color TIFF preview. "tiff" - Tagged Image File Format.
quality	The quality of JPEG compressed images. Must be in the range 0 (poor quality/small image) to 100 (perfect quality/very large image). For PDF images a value of "0" means no JPEG compression and ZIP compression will be used instead. For EPS this attribute is ignored.
dpi	The resolution of the output image in "dots per inch". A value of 0 means that the dpi is automatically calculated to preserve the width and height (as in centimeters or inches) of the source image.
compression	The compression scheme to use for TIFF images. Legal values are: "none" - no compression. "jpeg" - JPEG compression. "zip" - lossless ZIP compression.
renderpaths	If this is set to “1” the current clipping path (if any) will be applied and the background will be filled with white. (from eRez version 2.5)
chromasubsampling	Enables downsampling of color information during JPEG compression (default). When setting this attribute to the value “0” this will be disabled the file size will increase as much as 30 percent. But the color information is preserved at full resolution. Certain computer generated images may appear blurry unless this option is disabled.
tilesize	A value of “0” uses the standard “stripped” layout for the TIFF file (default). Specifying a tile size will using such as 128, 256 or 512 will create images organized as quadratic tiles which increases performance considerably depending on the size of the source images. This is highly recommended when working with images larger than 50 Mb and a “must” for images with a size of several gigabytes. Note: This format is in compliance with the TIFF specification but some older imaging applications may not be able to read it correctly.

Miscellaneous System Setting

The <erez-home> element

The erez-home element defines the public URL of the eRez sever. This is used when creating emails and building HTML page with the URL Builder. Erez-home only contains a single attribute URL.

Sample: <erez-home url=http://localhost:8080/erez2 />

The <emailer > element

The emailer element specifies various properties used when sending emails. If the “Admin” is set to a valid email address then an email is sent to that address when the server is started and when an error requires immediate attention. The settings for smtp and bcc are used when a user emails an image or folder. If “bcc” is set to a valid email address then a blind carbon copy of every email is sent to that address as well.

Sample:

<emailer

disabled="0"

smtp="smtp.yawah.com"

from="erez2@yawah.com"

replyto="devnull@yawah.com"

bcc="devnull@yawah.com"

admin="devnull@yawah.com"

Attributes for emailer:

disabled	Used to disable the email functions. By default this is set to “1”. To enable email change it to “0”.
smtp	The hostname or ip address of the outgoing SMTP server.
from	The default “from” email address.
replyto	The default “replyto” email address.
bcc	An email address that “Blind Carbon Copies” are sent to to every time an email sent.
admin	The email address of the eRez administrator,

The <flat-images > element

The flat-images element specifies the maximum uncompressed size in Mb allowable for a single-resolution image such as JPEG. The default value is 4 Mb and you should only increase it if you have a very powerful server with lots of memory.

Sample:

<flat-images

sizelimit="4"

The <imagefactory> element

The imagefactory element controls behavior of the real-time image-processor. Only one <imagefactory> element is allowed in the configuration file.

Sample: <imagefactory threads="2" cachelimit="100"/>

Attributes for imagefactory:

threads	The maximum number of concurrent image processing operations. The default value is 2. The optimal setting depends on the number of CPUs and available memory on the server.
cachelimit	The maximum size of each cache in mega bytes. When this attribute is present the server will check each cache every 5 minutes and delete the least recently used images until the total size of the images is equal or less to the cachelimit value. Make sure that every cache in the mount element is correct and contains nothing but eRez data before adding a cachelimit to your configuration.

The <downloadfactory> element

The downloadfactory element controls behavior of the asynchronous/download image-processor. Only one <downloadfactory> element is allowed in the configuration file.
Note that you must restart the servlet container in order for modifications to the downloadfactory element to take effect and alocate a minimum of 128MB RAM per thread to the Java Virtual Machine.

Sample: <downloadfactory threads="1" workpath="WEB-INF/download"/>

Attributes for downloadfactory:

threads	The maximum number of concurrent image processing operations. The default value is 1. The optimal setting depends on the number of CPUs and available memory on the server.
workpath	The path of a directory to temporarily hold the processed images and ZIP files. The sample value "WEB-INF/download" in order for eRez to work immediately after installation - but it is strongly recommended to change this to a folder outside the "erez" directory.

The <browser> element

The "browser" element controls the layout of the thumbnail listings. Only one <browser> element is allowed in the configuration file.

Sample: <browser rows="3" columns="4" width="110" imageheight="110" textheight="12"/>

Attributes for browser:

rows	The vertical number of thumbnails per page.
columns	The horisontal number of thumbnails per page.
width	The width in pixels for each thumbnail cell.
imageheight	The height in pixels of the image part of each thumbnail cell.
textheight	The height in pixels of the text part of each thumbnail cell.

From eRez version 1.1.7 rows and columns can be specified via parameters and the other properties are now controlled directly from the template.

The <iccprofiles> element

The "iccprofiles" element is used to specify paths to directories with external ICC profiles. You can add as many <iccprofiles> elements as you need.

Sample: <iccprofiles path="WEB-INF/icc profiles"/>

Attributes for iccprofiles:

path

The local path to the directory with ICC profiles. This can be a path to a local hard drive or a remote server like "\\HOST\SHARE\EREZ\PROFILES" on a Windows System. The sample configuration file that ships with the software uses a special path: "WEB-INF/sample images". "WEB-INF" is a special case supported in order to make the eRez Imaging Server work with the bundled profiles immediately after the installation.

The <mactext> element

The "mactext" element is used to identify and convert IPTC text data created on an Apple Macintosh computer. Because the Macintosh uses a special character set, national and special characters like the Danish æ,ø and å will be displayed incorrectly by eRez and other software packages on another platform. Because there is no simple way to detect if an IPTC record was created on a Macintosh we use a trigger mechanism. When one of the trigger characters is found in an IPTC text the entire chunk of text is treated as being "MacRoman".
The MacRoman character set is used for at least the following Mac OS, localizations: U.S., British, Canadian French, French, Swiss, French, German, Swiss German, Italian, Swiss Italian, Dutch, Swedish, Norwegian, Danish, Finnish, Spanish, Catalan, Portuguese, Brazilian, and the default International system.

This example will trigger on the danish characters 'æ', 'ø', 'å', 'Æ', 'Ø' and 'Å':

Attributes for trigger (mactext sub-element):

value

The hexadecimal representation of a character (see table below).

The Standard MacRoman character set.

The hotfolder element

The hotfolder element is used to specify the pause time between each scan for changes to the contents of shared folders.

Example: <hotfolders sleeptime="300" />

The attribute specifies the pause time in seconds. If there is no hotfolder element or sleeptime attribute a default value of 300 seconds (5 minutes) is used.

The encoding element

The encoding element is used to specify the encoding used when creating HTML document from velocity templates.

Example: <encoding charset="iso-8859-1" />

The attribute charset defines the encoding. Using a value of “” will use the standard encoding as obtained by Java from the underlying operating system. If there is no encoding element or charset attribute “iso-8859-1” will be used.

The metadatacache element

The metadatacache element is used to specify the maximum number of images to cache metadata for in memory.

Example: <metadatacache size="500" />

The attribute size specifies the maximum number of images to cache metadata for in memory. eRez will keep an up-to-date copy of the metadata for the most recently used images in RAM to increase the performance for frequently used images.

The encryption element

The encryption element is used to override the secret password used by eRez to build special URLs for use with slideshows and showcases for non-public folders and queries.

Example: <encryption key="snullerbat" />

The attribute key specifies the secret password used by eRez to build special URLs for use with slideshows and showcases for non-public folders and queries.